home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / cat3 / ifl / TIFFRGBAImage.z / TIFFRGBAImage
Encoding:
Text File  |  1998-10-20  |  15.9 KB  |  265 lines
  1.  
  2.  
  3.  
  4. TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee((((3333TTTT))))                    IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      TIFFRGBAImage - read and decode an image into a raster
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ####iiiinnnncccclllluuuuddddeeee <<<<ttttiiiiffffffffiiiioooo....hhhh>>>>
  13.      ttttyyyyppppeeeeddddeeeeffff uuuunnnnssssiiiiggggnnnneeeedddd cccchhhhaaaarrrr TTTTIIIIFFFFFFFFRRRRGGGGBBBBVVVVaaaalllluuuueeee;;;;
  14.      ttttyyyyppppeeeeddddeeeeffff ssssttttrrrruuuucccctttt ____TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee;;;;
  15.      iiiinnnntttt TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeeeOOOOKKKK((((TTTTIIIIFFFFFFFF**** ttttiiiiffff,,,, cccchhhhaaaarrrr eeeemmmmssssgggg[[[[1111000022224444]]]]))));;;;
  16.      iiiinnnntttt TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeeeBBBBeeeeggggiiiinnnn((((TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee**** iiiimmmmgggg,,,, TTTTIIIIFFFFFFFF**** ttttiiiiffff,,,, iiiinnnntttt ssssttttooooppppOOOOnnnnEEEErrrrrrrroooorrrr,,,, cccchhhhaaaarrrr eeeemmmmssssgggg[[[[1111000022224444]]]]))));;;;
  17.      iiiinnnntttt TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeeeGGGGeeeetttt((((TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee**** iiiimmmmgggg,,,, uuuuiiiinnnntttt33332222**** rrrraaaasssstttteeeerrrr,,,, uuuuiiiinnnntttt33332222 wwwwiiiiddddtttthhhh,,,, uuuuiiiinnnntttt33332222 hhhheeeeiiiigggghhhhtttt))));;;;
  18.      vvvvooooiiiidddd TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeeeEEEEnnnndddd((((TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee**** iiiimmmmgggg))));;;;
  19.  
  20. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  21.      The routines described here provide a high-level interface through which
  22.      TIFF images may be read into memory.  Images may be strip- or tile-based
  23.      and have a variety of different characteristics: bits/sample,
  24.      samples/pixel, photometric, etc.  Decoding state is encapsulated in a
  25.      _T_I_F_F_R_G_B_A_I_m_a_g_e structure making it possible to capture state for multiple
  26.      images and quickly switch between them.  The target raster format can be
  27.      customized to a particular application's needs by installing custom
  28.      routines that manipulate image data according to application
  29.      requirements.
  30.  
  31.      The default usage for these routines is: check if an image can be
  32.      processed using _T_I_F_F_R_G_B_A_I_m_a_g_e_O_K, construct a decoder state block using
  33.      _T_I_F_F_R_G_B_A_I_m_a_g_e_B_e_g_i_n, read and decode an image into a target raster using
  34.      _T_I_F_F_R_G_B_A_I_m_a_g_e_G_e_t, and then release resources using _T_I_F_F_R_G_B_A_I_m_a_g_e_E_n_d.
  35.      _T_I_F_F_R_G_B_A_I_m_a_g_e_G_e_t can be called multiple times to decode an image using
  36.      different state parameters.  If multiple images are to be displayed and
  37.      there is not enough space for each of the decoded rasters, multiple state
  38.      blocks can be managed and then calls can be made to _T_I_F_F_R_G_B_A_I_m_a_g_e_G_e_t as
  39.      needed to display an image.
  40.  
  41.      The generated raster is assumed to be an array of _w_i_d_t_h times _h_e_i_g_h_t 32-
  42.      bit entries, where _w_i_d_t_h must be less than or equal to the width of the
  43.      image (_h_e_i_g_h_t may be any non-zero size).  If the raster dimensions are
  44.      smaller than the image, the image data is cropped to the raster bounds.
  45.      If the raster height is greater than that of the image, then the image
  46.      data are placed in the lower part of the raster.  (Note that the raster
  47.      is assume to be organized such that the pixel at location (_x,_y) is
  48.      _r_a_s_t_e_r[_y*_w_i_d_t_h+_x]; with the raster origin in the lower-left hand corner.)
  49.  
  50.      Raster pixels are 8-bit packed red, green, blue, alpha samples.  The
  51.      macros _T_I_F_F_G_e_t_R, _T_I_F_F_G_e_t_G, _T_I_F_F_G_e_t_B, and _T_I_F_F_G_e_t_A should be used to
  52.      access individual samples.  Images without Associated Alpha matting
  53.      information have a constant Alpha of 1.0 (255).
  54.  
  55.      _T_I_F_F_R_G_B_A_I_m_a_g_e_G_e_t converts non-8-bit images by scaling sample values.
  56.      Palette, grayscale, bilevel, CMYK, and YCbCr images are converted to RGB
  57.      transparently.  Raster pixels are returned uncorrected by any colorimetry
  58.      information present in the directory.
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee((((3333TTTT))))                    IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  71.  
  72.  
  73.  
  74.      The paramater _s_t_o_p_O_n_E_r_r_o_r specifies how to act if an error is encountered
  75.      while reading the image.  If _s_t_o_p_O_n_E_r_r_o_r is non-zero, then an error will
  76.      terminate the operation; otherwise _T_I_F_F_R_G_B_A_I_m_a_g_e_G_e_t will continue
  77.      processing data until all the possible data in the image have been
  78.      requested.
  79.  
  80. AAAALLLLTTTTEEEERRRRNNNNAAAATTTTEEEE RRRRAAAASSSSTTTTEEEERRRR FFFFOOOORRRRMMMMAAAATTTTSSSS
  81.      To use the core support for reading and processing TIFF images, but write
  82.      the resulting raster data in a different format one need only override
  83.      the ``_p_u_t _m_e_t_h_o_d_s'' used to store raster data.  These methods are are
  84.      defined in the _T_I_F_F_R_G_B_A_I_m_a_g_e structure and initially setup by
  85.      _T_I_F_F_R_G_B_A_I_m_a_g_e_B_e_g_i_n to point to routines that pack raster data in the
  86.      default ABGR pixel format.  Two different routines are used according to
  87.      the physical organization of the image data in the file:
  88.      _P_l_a_n_a_r_C_o_n_f_i_g_u_r_a_t_i_o_n=1 (packed samples), and _P_l_a_n_a_r_C_o_n_f_i_g_u_r_a_t_i_o_n=2
  89.      (separated samples).  Note that this mechanism can be used to transform
  90.      the data before storing it in the raster.  For example one can convert
  91.      data to colormap indices for display on a colormap display.
  92.  
  93. SSSSIIIIMMMMUUUULLLLTTTTAAAANNNNEEEEOOOOUUUUSSSS RRRRAAAASSSSTTTTEEEERRRR SSSSTTTTOOOORRRREEEE AAAANNNNDDDD DDDDIIIISSSSPPPPLLLLAAAAYYYY
  94.      It is simple to display an image as it is being read into memory by
  95.      overriding the put methods as described above for supporting alternate
  96.      raster formats.  Simply keep a reference to the default put methods setup
  97.      by _T_I_F_F_R_G_B_A_I_m_a_g_e_B_e_g_i_n and then invoke them before or after each display
  98.      operation.  For example, the _t_i_f_f_g_t(1) utility uses the following put
  99.      method to update the display as the raster is being filled:
  100.  
  101.      static void
  102.      putContigAndDraw(TIFFRGBAImage* img, uint32* raster,
  103.          uint32 x, uint32 y, uint32 w, uint32 h,
  104.          int32 fromskew, int32 toskew,
  105.          unsigned char* cp)
  106.      {
  107.          (*putContig)(img, raster, x, y, w, h, fromskew, toskew, cp);
  108.          if (x+w == width) {
  109.           w = width;
  110.           if (img->orientation == ORIENTATION_TOPLEFT)
  111.               lrectwrite(0, y-(h-1), w-1, y, raster-x-(h-1)*w);
  112.           else
  113.               lrectwrite(0, y, w-1, y+h-1, raster);
  114.          }
  115.      }
  116.  
  117.      (the original routine provided by the library is saved in the variable
  118.      _p_u_t_C_o_n_t_i_g.)
  119.  
  120. SSSSUUUUPPPPPPPPOOOORRRRTTTTIIIINNNNGGGG AAAADDDDDDDDIIIITTTTIIIIOOOONNNNAAAALLLL TTTTIIIIFFFFFFFF FFFFOOOORRRRMMMMAAAATTTTSSSS
  121.      The _T_I_F_F_R_G_B_A_I_m_a_g_e routines support the most commonly encountered flavors
  122.      of TIFF.  It is possible to extend this support by overriding the ``_g_e_t
  123.      _m_e_t_h_o_d'' invoked by _T_I_F_F_R_G_B_A_I_m_a_g_e_G_e_t to read TIFF image data.  Details of
  124.      doing this are a bit involved, it is best to make a copy of an existing
  125.      get method and modify it to suit the needs of an application.
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee((((3333TTTT))))                    IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  137.  
  138.  
  139.  
  140. NNNNOOOOTTTTEEEESSSS
  141.      Samples must be either 1, 2, 4, 8, or 16 bits.  Colorimetric
  142.      samples/pixel must be either 1, 3, or 4 (i.e.  _S_a_m_p_l_e_s_P_e_r_P_i_x_e_l minus
  143.      _E_x_t_r_a_S_a_m_p_l_e_s).
  144.  
  145.      Palettte image colormaps that appear to be incorrectly written as 8-bit
  146.      values are automatically scaled to 16-bits.
  147.  
  148. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEESSSS
  149.      All routines return 1 if the operation was successful.  Otherwise, 0 is
  150.      returned if an error was encountered and _s_t_o_p_O_n_E_r_r_o_r is zero.
  151.  
  152. DDDDIIIIAAAAGGGGNNNNOOOOSSSSTTTTIIIICCCCSSSS
  153.      All error messages are directed to the _T_I_F_F_E_r_r_o_r(3T) routine.
  154.  
  155.      SSSSoooorrrrrrrryyyy,,,, ccccaaaannnn nnnnooootttt hhhhaaaannnnddddlllleeee %%%%dddd----bbbbiiiitttt ppppiiiiccccttttuuuurrrreeeessss.  The image had _B_i_t_s_P_e_r_S_a_m_p_l_e other
  156.      than 1, 2, 4, 8, or 16.
  157.  
  158.      SSSSoooorrrrrrrryyyy,,,, ccccaaaannnn nnnnooootttt hhhhaaaannnnddddlllleeee %%%%dddd----cccchhhhaaaannnnnnnneeeellll iiiimmmmaaaaggggeeeessss.  The image had _S_a_m_p_l_e_s_P_e_r_P_i_x_e_l
  159.      other than 1, 3, or 4.
  160.  
  161.      MMMMiiiissssssssiiiinnnngggg nnnneeeeeeeeddddeeeedddd """"PPPPhhhhoooottttoooommmmeeeettttrrrriiiiccccIIIInnnntttteeeerrrrpppprrrreeeettttaaaattttiiiioooonnnn"""" ttttaaaagggg.  The image did not have a
  162.      tag that describes how to display the data.
  163.  
  164.      NNNNoooo """"PPPPhhhhoooottttoooommmmeeeettttrrrriiiiccccIIIInnnntttteeeerrrrpppprrrreeeettttaaaattttiiiioooonnnn"""" ttttaaaagggg,,,, aaaassssssssuuuummmmiiiinnnngggg RRRRGGGGBBBB.  The image was missing
  165.      a tag that describes how to display it, but because it has 3 or 4
  166.      samples/pixel, it is assumed to be RGB.
  167.  
  168.      NNNNoooo """"PPPPhhhhoooottttoooommmmeeeettttrrrriiiiccccIIIInnnntttteeeerrrrpppprrrreeeettttaaaattttiiiioooonnnn"""" ttttaaaagggg,,,, aaaassssssssuuuummmmiiiinnnngggg mmmmiiiinnnn----iiiissss----bbbbllllaaaacccckkkk.  The image was
  169.      missing a tag that describes how to display it, but because it has 1
  170.      sample/pixel, it is assumed to be a grayscale or bilevel image.
  171.  
  172.      NNNNoooo ssssppppaaaacccceeee ffffoooorrrr pppphhhhoooottttoooommmmeeeettttrrrriiiicccc ccccoooonnnnvvvveeeerrrrssssiiiioooonnnn ttttaaaabbbblllleeee.  There was insufficient memory
  173.      for a table used to convert image samples to 8-bit RGB.
  174.  
  175.      MMMMiiiissssssssiiiinnnngggg rrrreeeeqqqquuuuiiiirrrreeeedddd """"CCCCoooolllloooorrrrmmmmaaaapppp"""" ttttaaaagggg.  A Palette image did not have a required
  176.      _C_o_l_o_r_m_a_p tag.
  177.  
  178.      NNNNoooo ssssppppaaaacccceeee ffffoooorrrr ttttiiiilllleeee bbbbuuuuffffffffeeeerrrr.  There was insufficient memory to allocate an
  179.      i/o buffer.
  180.  
  181.      NNNNoooo ssssppppaaaacccceeee ffffoooorrrr ssssttttrrrriiiipppp bbbbuuuuffffffffeeeerrrr.  There was insufficient memory to allocate an
  182.      i/o buffer.
  183.  
  184.      CCCCaaaannnn nnnnooootttt hhhhaaaannnnddddlllleeee ffffoooorrrrmmmmaaaatttt.  The image has a format (combination of
  185.      _B_i_t_s_P_e_r_S_a_m_p_l_e, _S_a_m_p_l_e_s_P_e_r_P_i_x_e_l, and _P_h_o_t_o_m_e_t_r_i_c_I_n_t_e_r_p_r_e_t_a_t_i_o_n) that can
  186.      not be handled.
  187.  
  188.      NNNNoooo ssssppppaaaacccceeee ffffoooorrrr BBBB&&&&WWWW mmmmaaaappppppppiiiinnnngggg ttttaaaabbbblllleeee.  There was insufficient memory to
  189.      allocate a table used to map grayscale data to RGB.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. TTTTIIIIFFFFFFFFRRRRGGGGBBBBAAAAIIIImmmmaaaaggggeeee((((3333TTTT))))                    IIIImmmmaaaaggggeeee FFFFoooorrrrmmmmaaaatttt LLLLiiiibbbbrrrraaaarrrryyyy CCCC++++++++ RRRReeeeffffeeeerrrreeeennnncccceeee MMMMaaaannnnuuuuaaaallll
  203.  
  204.  
  205.  
  206.      NNNNoooo ssssppppaaaacccceeee ffffoooorrrr PPPPaaaalllleeeetttttttteeee mmmmaaaappppppppiiiinnnngggg ttttaaaabbbblllleeee.  There was insufficient memory to
  207.      allocate a table used to map data to 8-bit RGB.
  208.  
  209. BBBBUUUUGGGGSSSS
  210.      Orientations other than bottom-left, or top-left are not handled
  211.      correctly.
  212.  
  213. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  214.      _l_i_b_t_i_f_f(3T), _T_I_F_F_O_p_e_n(3T), _T_I_F_F_R_e_a_d_R_G_B_A_I_m_a_g_e(3T)
  215.  
  216.  
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.